home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.2 Development Libraries / SGI IRIX 6.2 Development Libraries.iso / dist / complib.idb / usr / share / catman / p_man / cat3 / complib / dgegs.z / dgegs
Text File  |  1996-03-14  |  8KB  |  199 lines
  1.  
  2.  
  3.  
  4. DDDDGGGGEEEEGGGGSSSS((((3333FFFF))))                                                            DDDDGGGGEEEEGGGGSSSS((((3333FFFF))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      DGEGS - compute for a pair of N-by-N real nonsymmetric matrices A, B
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      SUBROUTINE DGEGS( JOBVSL, JOBVSR, N, A, LDA, B, LDB, ALPHAR, ALPHAI,
  13.                        BETA, VSL, LDVSL, VSR, LDVSR, WORK, LWORK, INFO )
  14.  
  15.          CHARACTER     JOBVSL, JOBVSR
  16.  
  17.          INTEGER       INFO, LDA, LDB, LDVSL, LDVSR, LWORK, N
  18.  
  19.          DOUBLE        PRECISION A( LDA, * ), ALPHAI( * ), ALPHAR( * ), B(
  20.                        LDB, * ), BETA( * ), VSL( LDVSL, * ), VSR( LDVSR, * ),
  21.                        WORK( * )
  22.  
  23. PPPPUUUURRRRPPPPOOOOSSSSEEEE
  24.      DGEGS computes for a pair of N-by-N real nonsymmetric matrices A, B:  the
  25.      generalized eigenvalues (alphar +/- alphai*i, beta), the real Schur form
  26.      (A, B), and optionally left and/or right Schur vectors (VSL and VSR).
  27.  
  28.      (If only the generalized eigenvalues are needed, use the driver DGEGV
  29.      instead.)
  30.  
  31.      A generalized eigenvalue for a pair of matrices (A,B) is, roughly
  32.      speaking, a scalar w or a ratio  alpha/beta = w, such that  A - w*B is
  33.      singular.  It is usually represented as the pair (alpha,beta), as there
  34.      is a reasonable interpretation for beta=0, and even for both being zero.
  35.      A good beginning reference is the book, "Matrix Computations", by G.
  36.      Golub & C. van Loan (Johns Hopkins U. Press)
  37.  
  38.      The (generalized) Schur form of a pair of matrices is the result of
  39.      multiplying both matrices on the left by one orthogonal matrix and both
  40.      on the right by another orthogonal matrix, these two orthogonal matrices
  41.      being chosen so as to bring the pair of matrices into (real) Schur form.
  42.  
  43.      A pair of matrices A, B is in generalized real Schur form if B is upper
  44.      triangular with non-negative diagonal and A is block upper triangular
  45.      with 1-by-1 and 2-by-2 blocks.  1-by-1 blocks correspond to real
  46.      generalized eigenvalues, while 2-by-2 blocks of A will be "standardized"
  47.      by making the corresponding elements of B have the form:
  48.              [  a  0  ]
  49.              [  0  b  ]
  50.  
  51.      and the pair of corresponding 2-by-2 blocks in A and B will have a
  52.      complex conjugate pair of generalized eigenvalues.
  53.  
  54.      The left and right Schur vectors are the columns of VSL and VSR,
  55.      respectively, where VSL and VSR are the orthogonal matrices which reduce
  56.      A and B to Schur form:
  57.  
  58.      Schur form of (A,B) = ( (VSL)**T A (VSR), (VSL)**T B (VSR) )
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. DDDDGGGGEEEEGGGGSSSS((((3333FFFF))))                                                            DDDDGGGGEEEEGGGGSSSS((((3333FFFF))))
  71.  
  72.  
  73.  
  74. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  75.      JOBVSL  (input) CHARACTER*1
  76.              = 'N':  do not compute the left Schur vectors;
  77.              = 'V':  compute the left Schur vectors.
  78.  
  79.      JOBVSR  (input) CHARACTER*1
  80.              = 'N':  do not compute the right Schur vectors;
  81.              = 'V':  compute the right Schur vectors.
  82.  
  83.      N       (input) INTEGER
  84.              The order of the matrices A, B, VSL, and VSR.  N >= 0.
  85.  
  86.      A       (input/output) DOUBLE PRECISION array, dimension (LDA, N)
  87.              On entry, the first of the pair of matrices whose generalized
  88.              eigenvalues and (optionally) Schur vectors are to be computed.
  89.              On exit, the generalized Schur form of A.  Note: to avoid
  90.              overflow, the Frobenius norm of the matrix A should be less than
  91.              the overflow threshold.
  92.  
  93.      LDA     (input) INTEGER
  94.              The leading dimension of A.  LDA >= max(1,N).
  95.  
  96.      B       (input/output) DOUBLE PRECISION array, dimension (LDB, N)
  97.              On entry, the second of the pair of matrices whose generalized
  98.              eigenvalues and (optionally) Schur vectors are to be computed.
  99.              On exit, the generalized Schur form of B.  Note: to avoid
  100.              overflow, the Frobenius norm of the matrix B should be less than
  101.              the overflow threshold.
  102.  
  103.      LDB     (input) INTEGER
  104.              The leading dimension of B.  LDB >= max(1,N).
  105.  
  106.      ALPHAR  (output) DOUBLE PRECISION array, dimension (N)
  107.              ALPHAI  (output) DOUBLE PRECISION array, dimension (N) BETA
  108.              (output) DOUBLE PRECISION array, dimension (N) On exit,
  109.              (ALPHAR(j) + ALPHAI(j)*i)/BETA(j), j=1,...,N, will be the
  110.              generalized eigenvalues.  ALPHAR(j) + ALPHAI(j)*i, j=1,...,N  and
  111.              BETA(j),j=1,...,N  are the diagonals of the complex Schur form
  112.              (A,B) that would result if the 2-by-2 diagonal blocks of the real
  113.              Schur form of (A,B) were further reduced to triangular form using
  114.              2-by-2 complex unitary transformations.  If ALPHAI(j) is zero,
  115.              then the j-th eigenvalue is real; if positive, then the j-th and
  116.              (j+1)-st eigenvalues are a complex conjugate pair, with
  117.              ALPHAI(j+1) negative.
  118.  
  119.              Note: the quotients ALPHAR(j)/BETA(j) and ALPHAI(j)/BETA(j) may
  120.              easily over- or underflow, and BETA(j) may even be zero.  Thus,
  121.              the user should avoid naively computing the ratio alpha/beta.
  122.              However, ALPHAR and ALPHAI will be always less than and usually
  123.              comparable with norm(A) in magnitude, and BETA always less than
  124.              and usually comparable with norm(B).
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. DDDDGGGGEEEEGGGGSSSS((((3333FFFF))))                                                            DDDDGGGGEEEEGGGGSSSS((((3333FFFF))))
  137.  
  138.  
  139.  
  140.      VSL     (output) DOUBLE PRECISION array, dimension (LDVSL,N)
  141.              If JOBVSL = 'V', VSL will contain the left Schur vectors.  (See
  142.              "Purpose", above.)  Not referenced if JOBVSL = 'N'.
  143.  
  144.      LDVSL   (input) INTEGER
  145.              The leading dimension of the matrix VSL. LDVSL >=1, and if JOBVSL
  146.              = 'V', LDVSL >= N.
  147.  
  148.      VSR     (output) DOUBLE PRECISION array, dimension (LDVSR,N)
  149.              If JOBVSR = 'V', VSR will contain the right Schur vectors.  (See
  150.              "Purpose", above.)  Not referenced if JOBVSR = 'N'.
  151.  
  152.      LDVSR   (input) INTEGER
  153.              The leading dimension of the matrix VSR. LDVSR >= 1, and if
  154.              JOBVSR = 'V', LDVSR >= N.
  155.  
  156.      WORK    (workspace/output) DOUBLE PRECISION array, dimension (LWORK)
  157.              On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  158.  
  159.      LWORK   (input) INTEGER
  160.              The dimension of the array WORK.  LWORK >= max(1,4*N).  For good
  161.              performance, LWORK must generally be larger.  To compute the
  162.              optimal value of LWORK, call ILAENV to get blocksizes (for
  163.              DGEQRF, DORMQR, and DORGQR.)  Then compute:  NB  -- MAX of the
  164.              blocksizes for DGEQRF, DORMQR, and DORGQR The optimal LWORK is
  165.              2*N + N*(NB+1).
  166.  
  167.      INFO    (output) INTEGER
  168.              = 0:  successful exit
  169.              < 0:  if INFO = -i, the i-th argument had an illegal value.
  170.              = 1,...,N:  The QZ iteration failed.  (A,B) are not in Schur
  171.              form, but ALPHAR(j), ALPHAI(j), and BETA(j) should be correct for
  172.              j=INFO+1,...,N.  > N:  errors that usually indicate LAPACK
  173.              problems:
  174.              =N+1: error return from DGGBAL
  175.              =N+2: error return from DGEQRF
  176.              =N+3: error return from DORMQR
  177.              =N+4: error return from DORGQR
  178.              =N+5: error return from DGGHRD
  179.              =N+6: error return from DHGEQZ (other than failed iteration)
  180.              =N+7: error return from DGGBAK (computing VSL)
  181.              =N+8: error return from DGGBAK (computing VSR)
  182.              =N+9: error return from DLASCL (various places)
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.